home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / format.n < prev    next >
Encoding:
Text File  |  1994-09-20  |  9.7 KB  |  265 lines
  1.  
  2.  
  3.  
  4. format(n)             Tcl Built-In Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      format - Format a string in the style of sprintf
  12.  
  13. SYNOPSIS
  14.      format _f_o_r_m_a_t_S_t_r_i_n_g ?_a_r_g _a_r_g ...?
  15. _________________________________________________________________
  16.  
  17.  
  18. INTRODUCTION
  19.      This command generates a formatted string in the same way as
  20.      the  ANSI C sprintf procedure (it uses sprintf in its imple-
  21.      mentation).   _F_o_r_m_a_t_S_t_r_i_n_g  indicates  how  to  format   the
  22.      result, using % conversion specifiers as in sprintf, and the
  23.      additional arguments, if any, provide values to  be  substi-
  24.      tuted  into the result.  The return value from format is the
  25.      formatted string.
  26.  
  27.  
  28. DETAILS ON FORMATTING
  29.      The command operates by scanning _f_o_r_m_a_t_S_t_r_i_n_g from  left  to
  30.      right.  Each character from the format string is appended to
  31.      the result string unless it is a percent sign.  If the char-
  32.      acter  is  a  %  then it is not copied to the result string.
  33.      Instead,  the  characters  following  the  %  character  are
  34.      treated as a conversion specifier.  The conversion specifier
  35.      controls the conversion of the next successive _a_r_g to a par-
  36.      ticular  format  and  the  result  is appended to the result
  37.      string in place of the conversion specifier.  If  there  are
  38.      multiple  conversion  specifiers  in the format string, then
  39.      each one controls the conversion of one additional _a_r_g.  The
  40.      format  command  must be given enough _a_r_gs to meet the needs
  41.      of all of the conversion specifiers in _f_o_r_m_a_t_S_t_r_i_n_g.
  42.  
  43.      Each conversion specifier may contain up  to  six  different
  44.      parts: an XPG3 position specifier, a set of flags, a minimum  |
  45.      field width, a precision, a length modifier, and  a  conver-
  46.      sion  character.   Any of these fields may be omitted except
  47.      for the conversion character.  The fields that  are  present
  48.      must  appear in the order given above.  The paragraphs below
  49.      discuss each of these fields in turn.
  50.  
  51.      If the % is followed by a decimal number  and  a  $,  as  in  |
  52.      ``%2$d'',  then  the  value to convert is not taken from the  |
  53.      next sequential argument.  Instead, it  is  taken  from  the  |
  54.      argument indicated by the number, where 1 corresponds to the  |
  55.      first _a_r_g.  If the conversion  specifier  requires  multiple  |
  56.      arguments because of * characters in the specifier then suc-  |
  57.      cessive arguments are used, starting with the argument given  |
  58.      by  the number.  This follows the XPG3 conventions for posi-  |
  59.      tional specifiers.  If there are any  positional  specifiers  |
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. format(n)             Tcl Built-In Commands
  71.  
  72.  
  73.  
  74.      in  _f_o_r_m_a_t_S_t_r_i_n_g  then  all  of the specifiers must be posi-  |
  75.      tional.
  76.  
  77.      The second portion of a conversion specifier may contain any
  78.      of the following flag characters, in any order:
  79.  
  80.      -         Specifies that the converted  argument  should  be
  81.                left-justified  in its field (numbers are normally
  82.                right-justified with leading spaces if needed).
  83.  
  84.      +         Specifies that a number should always  be  printed
  85.                with a sign, even if positive.
  86.  
  87.      _s_p_a_c_e     Specifies that a space  should  be  added  to  the
  88.                beginning  of  the  number  if the first character
  89.                isn't a sign.
  90.  
  91.      0         Specifies that the number should be padded on  the
  92.                left with zeroes instead of spaces.
  93.  
  94.      #         Requests an alternate output form.  For  o  and  O
  95.                conversions  it guarantees that the first digit is
  96.                always 0.  For  x  or  X  conversions,  0x  or  0X
  97.                (respectively)  will  be added to the beginning of
  98.                the result unless it is zero.  For  all  floating-
  99.                point  conversions  (e, E, f, g, and G) it guaran-
  100.                tees that the result always has a  decimal  point.
  101.                For g and G conversions it specifies that trailing
  102.                zeroes should not be removed.
  103.  
  104.      The third portion of a conversion specifier is a number giv-
  105.      ing  a minimum field width for this conversion.  It is typi-
  106.      cally used to make columns line up in tabular printouts.  If
  107.      the  converted  argument  contains fewer characters than the
  108.      minimum field width then it will be padded so that it is  as
  109.      wide as the minimum field width.  Padding normally occurs by
  110.      adding extra spaces on the left of the  converted  argument,
  111.      but  the  0  and - flags may be used to specify padding with
  112.      zeroes on the left or with  spaces  on  the  right,  respec-
  113.      tively.  If the minimum field width is specified as * rather
  114.      than a number, then the next argument to the format  command
  115.      determines  the  minimum  field  width; it must be a numeric
  116.      string.
  117.  
  118.      The fourth portion of a conversion specifier is a precision,
  119.      which consists of a period followed by a number.  The number
  120.      is used in different ways for different conversions.  For e,
  121.      E,  and  f  conversions it specifies the number of digits to
  122.      appear to the right of the  decimal  point.   For  g  and  G
  123.      conversions  it  specifies  the  total  number  of digits to
  124.      appear, including those on both sides of the  decimal  point
  125.      (however, trailing zeroes after the decimal point will still
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. format(n)             Tcl Built-In Commands
  137.  
  138.  
  139.  
  140.      be omitted unless the  #  flag  has  been  specified).   For
  141.      integer conversions, it specifies a mimimum number of digits
  142.      to print (leading zeroes will be added if necessary).  For s
  143.      conversions it specifies the maximum number of characters to
  144.      be printed; if the string  is  longer  than  this  then  the
  145.      trailing  characters  will  be dropped.  If the precision is
  146.      specified with * rather than a number then the next argument
  147.      to the format command determines the precision; it must be a
  148.      numeric string.
  149.  
  150.      The fourth part of a conversion specifier is a length modif-
  151.      ier, which must be h or l.  If it is h it specifies that the
  152.      numeric value should be truncated to a 16-bit  value  before
  153.      converting.   This  option is rarely useful.  The l modifier
  154.      is ignored.
  155.  
  156.      The last thing in a conversion specifier  is  an  alphabetic
  157.      character  that  determines  what kind of conversion to per-
  158.      form.  The following  conversion  characters  are  currently
  159.      supported:
  160.  
  161.      d         Convert integer to signed decimal string.
  162.  
  163.      u         Convert integer to unsigned decimal string.
  164.  
  165.      i         Convert integer to  signed  decimal  string;   the
  166.                integer may either be in decimal, in octal (with a
  167.                leading 0) or in hexadecimal (with a leading 0x).
  168.  
  169.      o         Convert integer to unsigned octal string.
  170.  
  171.      x or X    Convert integer to  unsigned  hexadecimal  string,
  172.                using   digits   ``0123456789abcdef''  for  x  and
  173.                ``0123456789ABCDEF'' for X).
  174.  
  175.      c         Convert  integer  to  the   8-bit   character   it
  176.                represents.
  177.  
  178.      s         No conversion; just insert string.
  179.  
  180.      f         Convert floating-point number  to  signed  decimal
  181.                string of the form _x_x._y_y_y, where the number of _y's
  182.                is determined by the precision (default:  6).   If
  183.                the  precision  is 0 then no decimal point is out-
  184.                put.
  185.  
  186.      e or e    Convert floating-point number to scientific  nota-
  187.                tion  in  the  form _x._y_y_ye+__z_z, where the number of
  188.                _y's is determined by the precision  (default:  6).
  189.                If  the  precision  is  0 then no decimal point is
  190.                output.  If the E form is used then E  is  printed
  191.                instead of e.
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. format(n)             Tcl Built-In Commands
  203.  
  204.  
  205.  
  206.      g or G    If the exponent is less than -4 or greater than or
  207.                equal  to  the  precision,  then convert floating-
  208.                point number as for %e or %E.   Otherwise  convert
  209.                as for %f.  Trailing zeroes and a trailing decimal
  210.                point are omitted.
  211.  
  212.      %         No conversion: just insert %.
  213.  
  214.      For the numerical conversions the argument  being  converted
  215.      must be an integer or floating-point string; format converts
  216.      the argument to binary and then converts it back to a string
  217.      according to the conversion specifier.
  218.  
  219.  
  220. DIFFERENCES FROM ANSI SPRINTF
  221.      The behavior of the format command is the same as the ANSI C  |
  222.      sprintf procedure except for the following differences:       |
  223.  
  224.      [1]                                                                ||
  225.           %p and %n specifiers are not currently supported.
  226.  
  227.      [2]  For %c conversions  the  argument  must  be  a  decimal
  228.           string, which will then be converted to the correspond-
  229.           ing character value.
  230.  
  231.      [3]  The l modifier is ignored;  integer values  are  always  |
  232.           converted as if there were no modifier present and real  |
  233.           values are always converted as if the l  modifier  were  |
  234.           present  (i.e.  type  double  is  used for the internal  |
  235.           representation).  If the h modifier is  specified  then  |
  236.           integer  values  are  truncated to short before conver-  |
  237.           sion.
  238.  
  239.  
  240. KEYWORDS
  241.      conversion specifier, format, sprintf, string, substitution
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Tcl                                                             4
  262.  
  263.  
  264.  
  265.